home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Pascal Super Library
/
Pascal Super Library (CW International)(1997).bin
/
SHELLS
/
SZ2
/
AINTRO.DOC
< prev
next >
Wrap
Text File
|
1992-08-31
|
13KB
|
359 lines
************
INTRODUCTION
************
SHAZAM lets you define the entire interface of a Turbo Vision
application in a simple ASCII file.
With a few keywords and a easy syntax, you can define and test
anything from a simple test program to the TP 6.0 IDE, including
online help, hints and context-sensitive StatusLines.
You only need the [ SUBMENU ] and [ STATUS ] keywords to develop an
interface. Other keywords and switches give you control over every
aspect of how a program is generated.
You can develop and maintain Turbo Vision software using SHAZAM, too,
not just generate interfaces. Use the Dialog Editor to paint
screens and the [ DIALOG ] keyword to include them; the [ UNIT ]
keyword for automatic overlays and registration.
By flipping switches, you can change your program from pure code (for
fast development) to a fully resourced, overlaid program with
swap-to-disk capability for EXEC calls.
Keywords and switches are covered later. First, let's take a look at
the process of creating a program. This will help you understand
what the keywords and switches are, and why they exist.
***************
THE BIG PICTURE
***************
Application Elements Program Elements
*.HLP *.EXE
*.DLG *.DEF *.TXT *.REZ *.OVR *.$$$
┌───────┐ ┌──────┬──────┐ ┌───────────┬────────┬────────┐
│ │ │Menus │Online│ │ │Program │Unitize │
│Dialogs│ │Status│ Help │ │ Resources │ & │ & │
│ │ │Hints │ │ │ │Overlays│ExecSwap│
└───┬───┘ └──┬───┴─┬──┬─┘ └─────┬─────┴───┬────┴───┬────┘
│ ├─────┘ │ └─────────┼────────┘
│ │ │ │
╔═══╧══╗ ╔══╧═══╗ ╔══╧═════╗ ╔════╧════╗
║Dialog║ ║ Text ║ ║ Help ║ ║ Code ║
║Editor║ ║Editor║ ║Compiler║ ║Generator║
╚═══╤══╝ ╚═══╤══╝ ╚════╤═══╝ ╚════╤════╝
└─────────────┴────┬────┴─────────────────────┘
│
▐▀▀▀▀▀▀▀▀▌
▐ SHAZAM ▌
▐▄▄▄▄▄▄▄▄▌
This little diagram might make you wonder: Can SHAZAM create your
application as a fully resourced program with overlays, using
multiple and/or foreign language sets of MenuBars, Context-sensitive
StatusLines, Hints and Dialogs, compile Help Text, ensure updated
resource values and by-the-way encapsulate everything so we can
swap-to-disk for EXEC calls with minimum memory overhead?
Yes.
Load any example definition, then press "Ctrl-F9" to run it.
******************
EVOLVING A PROGRAM
******************
Let's look at the how you create a program by hand, then using SHAZAM.
BY HAND
=======
First, we need an interface - something to start with. Create a
MenuBar, match up all those "NIL" and "Parentheses". Now, for each
interface item (cmXX), extend HandleEvent to call a dummy routine and
create the routine (a window or MsgBox), so we can see something
happen. Next, figure out a help context for the drop-down menus, so
we can at least have hints -- oops, gotta extend a new StatusLine
object, so the hints show up. Let's plug-in the "HelpFile" unit and
dummy up some online Help, so the "F1" does something. Look-up and
re-use the help contexts we already defined -- oops, we don't need to
define them anymore, the help compiler does it for us, so take'em
out. Don't forget to extend "GetPalette", to avoid the RED + WHITE +
BLINK when help pops up.
Normally, you'd have to do all the above by hand, even for a three
line program. A partial list of the things you need to hand-code:
MenuBar - Items & SubMenus
StatusLine - Items & Context ranges
(PNewStatusLine w/Load & Store, for hints/resources)
cmXX - Command constant names & values
Params - MenuBar shortcuts
Hints - One-Liners for MenuBar & Dialog controls
kbXX - Which keyboard consta
hcXX - help context
Using SHAZAM
============
The following statements do ALL the above, in about 60 seconds:
[ SUBMENU ] File ;;file management
Open ;;open a new file
Save ;;save text in current window
Try a "copy & paste" of the three lines above into a file named
SAMPLE.DEF, then press the Ctrl-F9 key to run the example. You'll
note that SHAZAM does a number of little "extras", such as adding
context sensitive StatusLines where needed (these "extras" can be
controlled via switches or the SETUP|Code dialog).
By now, you're probably got the idea that the distance from program
"Conception to Construction" just got shorter! As soon as you run
through the ADEMO*.DEF series, putting meat on the bones of your
applications is going to get a lot easier. You should be able to get
a new interface up & running almost as fast as you can think it up.
************
FLESH IT OUT
************
If you look at the source code for any generated definition, you'll
see that command constants, help contexts and "dummy routines" are
generated by SHAZAM for each Menu or Status item. An entry is made
in the generated HandleEvent, with each "cmXX" symbol matching a call
to an "hdXX" routine of the same name.
Look at the *.HE file from any generated example.
Unless you say otherwise, the matching "hdXX" is a "dummy routine",
created by SHAZAM, so generated programs will compile (and do
something).
Of course, if you could make the Application^.HandleEvent call your
own code, instead of dummy routines, SHAZAM could be used for actual
programs, to develop and maintain software.
Somehow, you have to signal SHAZAM that an element of a Menu/Status
item is either the real thing or must be dummied up. That's where
keywords and/or symbols come into play.
MENU/STATUS ITEMS
-----------------
A quick glossary of terms:
cmXX - A command constant/symbol
kbXX - A keyboard constant/symbol
hdXX - A HandlecommanD routine (actual or dummy)
hbXX - A HandleBroadcast routine
hcXX - A help context constant/symbol (MENU only)
You can signal that an item is "real" by
1. Auto-scan of related *.EVT file
2. Keywords - [ INTERNAL ] and [ EXTERNAL ]
3. Symbols - "^^" (internal) and "%%" (external)
AUTO-SCAN
---------
If the matching *.EVT files exists, it is scanned for command and/or
broadcast routines which have "hd" or "hb" prefixes. If found, a
matching "cmXX" is created, and entries will be made to the generated
HandleEvent.
Each "hdXX" is added to HandleEvent, under the "evCommand" mask; look
at a generated *.HE file and you will find a "HandlecommanD" section.
Each "hbXX" is added to HandleEvent, under the "evBroadcast" mask.
Generate BCAST.DEF and look at "HandleBroadcast" in the BCAST.HE file.
This works dandy, since these are always at the Application level.
But you may want to move code into units or include files, so we need
another way to "reserve" names for cmXX, hdXX and hbXX symbols.
[ INTERNAL ] or [ EXTERNAL ]
----------------------------
Remember, when a program is generated, each "XX" name generates a
matched pair of "cmXX" and "hdXX" for HandleEvent. And it's a given
that any MenuBar, MenuBox or StatusLine item is going to be handled
by either the Application or a TView descendant.
You need to decide: Is the event handled by the Application or an
object? If by an object, like TFileEditor, it's [INTERNAL]. If by
the Application, it's [EXTERNAL].
[ INTERNAL ] stuff we don't have to worry about, other than to tell
SHAZAM that no cmXX or hdXX routines need to be created.
[ EXTERNAL ] routines are what we're going to be working with. They
can be anywhere -- in an include file or a unit. You'll find some
useful "[ EXTERNAL ]" routines in the GENERAL unit (see GEVENT.INT)
for common functions like "hdTile", "hdSaveDesktop", etc.
With either keyword, all you're doing is making a "reservation" for a
pair of "cmXX" and "hdXX" names. Just make a list under each
keyword. The equivalent symbols, "^^" for [ INTERNAL ] and "%%" for
[ EXTERNAL ], can be used right in the definition file.
EXAMPLES
--------
Assuming we have the routine "hdOpen" in an include file or a unit,
the following [ EXTERNAL ] examples are identical:
SYMBOL EXAMPLE
[submenu] file
%%Open
Save
KEYWORD EXAMPLE
[external]
Open
[submenu] file
Open
Save
Assuming we have an object which has a built-in "Save" function, such
as a TFileEditor, the following [ INTERNAL ] examples are identical:
SYMBOL EXAMPLE
[submenu] file
Open
^^Save
KEYWORD EXAMPLE
[internal]
Save
[submenu] file
Open
Save
*.EVT REVISITED
Remember that this file is scanned for prefixed routines. The
HandlecommanD (hdXX) were covered earlier; now let's look at
HandleBroadcast (hbXX).
The [ BROADCAST ] keyword
=========================
By nature, broadcasts are never called directly from a Menu or Status
item. They are either standard, such as "hbCommandSetChanged" or
defined & called by you (or your objects) via the Message function.
If a routine name prefixed with "hb" is found, it is added to the
generated HandleEvent under "HandleBroadcast".
If you want the code to be in an include file or a unit, you use the
[ BROADCAST ] keyword to signal that the routine exists, but is not
in the *.EVT file. The "HandleBroadcast" call will be made.
See BCAST.DEF for details.
**************
NAMES OF FILES
**************
Using SHAZAM, there are two types of files:
[X] Custom - What you create and maintain
[X] Generated - by SHAZAM
By default, all components and generated files are kept in separate
include files. You can use the SETUP dialog to put all code into a
single *.PAS file.
CUSTOM FILES
============
These are the files which you create and maintain. If you've loaded
any of the more advanced definitions (*.DEF), you'll note that when
Desktop is empty, all these files are loaded for you; this can be
changed with the SETUP|IDE dialog. Also, the system menu contains
options to load and clear these files from the Desktop.
*.DEF - the definition file
*.INC - general purpose include file
*.VIR - your application methods
*.EVT - event routines for HandleBroadcast & HandleCommand
*.TXT - Help text (optional)
*.DLG - Dialog Editor files (interactive)
GENERATED FILES
===============
These are organized as primary and secondary files. Order and
placement vary, depending on whether your program is currently a
code, resource or combination-type application.
*.pas - the program
*.OV - list of units to overlay
*_I.pas - initialization for names, overlays & memory remapping.
*.KB - kbXX used by the definition, plus kbCtrl? added by SHAZAM
*.CM - cmXX (command constants) generated by SHAZAM
*.RZ - "RezFile" object, plus code to open & close resource file
*_X.pas - hcXX symbols, from Help Compiler
*_U.pas - unitized application
*.US - list of units for USES clause
*.OB - declaration of the application object
*.MB - MenuBar(s) (CODE only)
*.SL - StatusLine(s) (CODE only)
*.HN - Hint set(s) (CODE only)
*.GE - GetEvent, GetPalette and OutOfMemory methods
*.INC - CUSTOM COMPONENT
*.VIR - CUSTOM COMPONENT
*.HE - HandleEvent method (HandleBroadcast & HandleCommand)
*.EVT - CUSTOM COMPONENT
*.EV - Dummy routines
*.DC - documentation, summary of generated application
RESOURCES
=========
If the application uses resources, the Menu, Status and Hint elements
are separated into UNITS, to allow construction of larger, more
detailed interfaces. The following are created:
*_R.pas - program to create/update resources
*_M.pas - unit for MenuBar(s)
*.MB - MenuBar(s) (REZ only)
*_S.pas - unit for StatusLine(s)
*.SL - StatusLine(s) (REZ only)
*_H.pas - unit for Hint set(s)
*.HN - Hint set(s) (REZ only)
****************
COMPILER SYMBOLS
****************
The following compiler symbols are automatically added by SHAZAM:
{$DEFINE defname} - name of *.DEF file
{$DEFINE code} - if all framework elements are set to "code"
{$DEFINE resource} - if all framework elements are set to "REZ"
{$DEFINE execswap} - if the ExecSwap ("/x+") option is set